의정부 기록공유관 아이템 검색 (홈페이지 제공용)

• URI : /api/search
• Method : GET
• Parameter Type : query string
• 개발서버 기준 요청 URL
  • https://uilib-user.eco-dev.kr/archive/api/search

개발 서버 : https://uilib-user.eco-dev.kr/archive

운영 서버 : https://www.uilib.go.kr/archive

• 현재 배포되지 않음

📗 Query Parameters

필드 상세 설명

keyword

검색어

💡 결과내 재검색 키워드인 withInKeyword 입력시에는 keyword 가 필수 입니다.

sortField

정렬 기준이 되는 필드를 지정합니다.

• ca: 등록일
• an: 아이템명 ([대괄호] 무시)

orderType

정렬 순서를 지정합니다.

• as: 오름차순 정렬
• de: 내림차순 정렬

page

• 조회할 페이지 번호
• 1부터 시작하며 최대 100페이지까지 조회 가능

sizePerPage

• 한 페이지에 표시할 항목 수
• 최소 1개부터 최대 50개까지 설정 가능

📗 요청 예시

GET /api/search?keyword=검색어&withInKeyword=재검색어&sortField=ca&orderType=DESC&page=1&sizePerPage=20

Javascript Fetch 기준 예시

const url = 'https://uilib-user.eco-dev.kr/archive/api/search';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

💬 응답 필드

✅ Response Body 구조 예시 - 200 OK

{
  "searchList": [...],
  "totalCount": 100,
  "totalPage": 10
}

Root 객체

Item 객체

필드 상세 설명

itemIdentifier

아이템 코드 (상세보기 이동시 사용)

상세 보기 URL : {도메인주소} + '/page/items/' + {아이템 코드}

호출 예시

https://uilib-user.eco-dev.kr/archive/page/items/IT00002594

produceYear

생산연도

null 혹은 빈값 반환시 미상 으로 표기

thumbnailFileName

썸네일 이미지 파일명

이미지 표기시 {도메인주소}+'/upload/image/th/' + {파일명}

호출 예시

https://uilib-user.eco-dev.kr/archive/upload/image/th/0933e2764e554b1395f04c917ec4f722.png

❌ Response Body 구조 예시 - 400 Bad Request

{
  "errorCode": null,
  "message": "메세지",
  "errorResult": null,
  "fieldErrors": [...]
}

📜 응답 예시

성공시

• 200 OK - 검색결과가 없을때

{
  "totalCount": 0,
  "searchList": [],
  "totalPage": 1
}

• 200 OK - 검색결과 존재시

{
  "totalCount": 3,
  "searchList": [
    {
      "itemIdentifier": "IT00002594",
      "itemName": "의정부 기록공유관 데이터 테스트용",
      "produceYear": "2005",
      "thumbnailFileName": "0933e2764e554b1395f04c917ec4f722.png",
      "creatorDetailInfo": "기록발굴단 외 1건",
      "archiveSourceInfo": "고대미상 외 1건"
    },
    {
      "itemIdentifier": "IT00002550",
      "itemName": "[의정부 전투와 전후 복구] 전후 도시 재건과 미군 주둔",
      "produceYear": null,
      "thumbnailFileName": null,
      "creatorDetailInfo": "의정부기록공유관",
      "archiveSourceInfo": "의정부기록공유관"
    },
    {
      "itemIdentifier": "IT00002556",
      "itemName": "[의정부 주둔 미군 캠프] 캠프 레드클라우드(CRC) : 도심 본부기지의 역할과 철수",
      "produceYear": null,
      "thumbnailFileName": null,
      "creatorDetailInfo": "의정부기록공유관",
      "archiveSourceInfo": "의정부기록공유관"
    }
  ],
  "totalPage": 1
}

실패시

💡 4xx 로 응답시 front-end 에서 잘못된 요청을 한 경우 이니

유저에게 메세지를 출력하지 말고 (화면단)코드를 확인 후 수정 바랍니다.

• 400 Bad Request - 잘못된 범위 혹은 지정되지 않은 문자를 입력시

{
  "errorCode": null,
  "message": "정렬 필드는 ca an 중 하나여야 합니다.",
  "errorResult": null,
  "fieldErrors": null
}

다른 예시

{
  "errorCode": null,
  "message": "결과내 재검색 키워드를 입력하려면 통합검색 키워드를 함께 입력해야 합니다.",
  "errorResult": null,
  "fieldErrors": null
}

• 400 Bad Request - 잘못된 query string 값 입력 - 문자열을 int 에 넣을 때

{
  "errorCode": null,
  "message": "Invalid Input Value",
  "errorResult": null,
  "fieldErrors": [
    {
      "codes": [
        "typeMismatch.searchRequest.page",
        "typeMismatch.page",
        "typeMismatch.int",
        "typeMismatch"
      ],
      "arguments": [
        {
          "codes": [
            "searchRequest.page",
            "page"
          ],
          "arguments": null,
          "defaultMessage": "page",
          "code": "page"
        }
      ],
      "defaultMessage": "Failed to convert property value of type 'java.lang.String' to required type 'int' for property 'page'; For input string: \"222222z\"",
      "objectName": "searchRequest",
      "field": "page",
      "rejectedValue": "222222z",
      "bindingFailure": true,
      "code": "typeMismatch"
    }
  ]
}

💡 5xx status 반환시

서버 오류 혹은 일시적인 서버중단으로 적당한 메세지를 유저에게 출력 바랍니다.